GitHub - proticom/gnosys: Persistent memory for AI agents

Gnosys — One Brain. Zero Context Bloat.

Gnosys gives AI agents persistent memory that survives across sessions, projects, and machines.

Gnosys is sandbox-first: a persistent background process holds the database connection while agents import a tiny helper library and call memory operations like normal code — no MCP schemas, no round-trips, near-zero context cost. The central brain at ~/.gnosys/gnosys.db unifies all projects, user preferences, and global knowledge. Federated search ranks results across scopes with tier boosting and recency awareness. The Web Knowledge Base turns any website into a searchable knowledge base for serverless chatbots — pre-computed JSON index, zero runtime dependencies. Multimodal ingestion handles PDFs, images, audio, and video. Portfolio Dashboard gives a bird's-eye view of all projects. Process tracing builds call chains from source code. Dream Mode consolidates knowledge during idle time. One-command export regenerates a full Obsidian vault.

It also runs as a CLI and a complete MCP server that drops straight into Cursor, Claude Desktop (Chat / Cowork / Code), Claude Code, Codex, Gemini CLI, Antigravity, or any MCP client.

No vector DBs. No black boxes. No external services. Just SQLite and optional Obsidian export — the way knowledge should be.

Why Gnosys?

Most "memory for LLMs" solutions use vector databases, embeddings, or proprietary services. They're opaque — you can't see what the model remembers, can't edit it, can't version it, can't share it.

Gnosys takes a different approach: the central brain is a single SQLite database (~/.gnosys/gnosys.db) with sub-10ms reads. SQLite is the sole source of truth — no dual-write, no scattered files. When you want a human-readable view, gnosys export generates a full Obsidian vault on demand. History lives in the audit_log table, not Git.

What makes it different:

Sandbox-first — persistent background process + helper library. Agents call gnosys.add() / gnosys.recall() like regular code. No MCP overhead, near-zero context cost.
Centralized brain — single ~/.gnosys/gnosys.db unifies all projects with project_id + scope columns. No more per-project silos.
Federated search — tier-boosted search across project (1.5x) > user (1.0x) > global (0.7x) scopes with recency and reinforcement boosts.
Web Knowledge Base — gnosys web build turns any website into a searchable knowledge base for serverless chatbots. Powers Sir Chats-A-Lot.
Dream Mode — idle-time consolidation: confidence decay, self-critique, summary generation, relationship discovery. Never deletes — only suggests reviews.
Transparent — DB-only with on-demand Obsidian export. gnosys export generates a full vault of human-readable .md files whenever you need them.
Portfolio Dashboard — gnosys status for one project, gnosys status --global for all projects, gnosys status --web for an HTML dashboard. gnosys update-status runs a guided 8-section checklist for AI agents.
Multimodal ingestion — ingest PDFs, images, audio, and video. Extraction pipelines for each media type feed structured memories into the central DB.
Hybrid Search — FTS5 keyword + semantic embeddings via Reciprocal Rank Fusion (RRF).
Multi-project — MCP roots + per-tool projectRoot routing + central project registry. Multiple Cursor windows, zero conflicts.
Process tracing — gnosys trace <dir> builds call chains from source code with leads_to, follows_from, and requires relationships.
Reflection API — gnosys.reflect(outcome) updates confidence and consolidates memories based on real-world outcomes.
Bulk import — CSV, JSON, JSONL. Import entire datasets in seconds.
Obsidian-native — gnosys export generates a full vault with YAML frontmatter, [[wikilinks]], summaries, and graph data.
Multi-machine sync — share your gnosys.db across machines via NAS or shared drive. Remote NAS is the canonical source of truth; local DB is an offline-resilience cache. Built-in conflict detection with skip-and-flag resolution. Run gnosys setup remote to set up.
MCP-compatible — also runs as a full MCP server that drops into Cursor, Claude Desktop (Chat / Cowork / Code), Claude Code, Codex, Gemini CLI, Antigravity, or any MCP client.
Zero infrastructure — no external databases, no Docker (unless you want it), no cloud services. Just npm install.

For the complete CLI reference and detailed guides, see the User Guide.

Quick Start

# 1. Install globally
npm install -g gnosys

# 2. Run the setup wizard (configures provider, API key, and IDE)
gnosys setup

# 3. Initialize a project
cd your-project
gnosys init

# 4. Start adding memories
gnosys add "We chose PostgreSQL over MySQL for its JSON support"
gnosys recall "database selection"

Postinstall hook: After npm install -g gnosys, a postinstall script automatically runs gnosys setup if no configuration is detected, so first-time users are guided through provider and IDE setup immediately.

Multi-machine? Set GNOSYS_GLOBAL to a cloud-synced folder (iCloud Drive, Dropbox, OneDrive) and both machines share the same brain. After updating, run gnosys upgrade — it re-syncs all projects, regenerates agent rules, and warns other machines to upgrade too. See the User Guide — Installation & Setup for the full walkthrough, memory scopes, and multi-machine setup.

Agent / Helper Library

import { gnosys } from "./gnosys-helper";   // generated once via: gnosys helper generate

await gnosys.add("We use conventional commits");
const ctx = await gnosys.recall("auth decisions");
await gnosys.reinforce("payment logic");

The helper auto-starts the sandbox if it's not running. No MCP required.

Interactive Chat (TUI)

gnosys chat opens a memory-aware terminal chat. Every prompt triggers federated recall against the central brain; the LLM sees relevant memories in context and cites them in its answers.

gnosys chat                    # new session
gnosys chat --resume <id>      # continue an earlier session
gnosys chat --list             # see all sessions
gnosys chat --search <query>   # full-text search across session logs

Free-text or slash commands. "remember that flag default is OFF" works the same as /remember flag default is OFF. The TUI also recognizes "what did we decide about ULIDs?" → /recall, "thanks, that's all" → /quit. Destructive intents always confirm; non-destructive ones auto-accept after 5 confirmations of the same pattern.

24 slash commands across reading, recall, writing, focus, and polish — type /help inside the TUI for the full list. Highlights:

/pin <id>, /scope, /threshold, /recall <q> — tune what shows up in context
/remember <text>, /save-turn, /attach <file> — promote chat content to gnosys memory (PDFs, images, audio all auto-pin to the session)
/focus <topic>, /branch, /resume-focus — replace the "new chat" model with cheap focus boundaries; one continuous session log, instant pivot
/export <file.md>, /search-chats <q>, /dream-here — round-trip the session, find old chats, or trigger a focused dream cycle

Multiple choice. When the model needs you to pick from a small set, it emits a fenced gnosys-choose block. The TUI parses it and shows an arrow-key selectable list — provider-agnostic, no tool-use API required.

Sessions live as append-only JSONL at ~/.gnosys/chat-sessions/; promoted memories carry session:<id>, from-chat:true, and source:remember|save-turn|auto|attach provenance tags so you can find them later via federated search.

Per-Project Bundles

Move a single project's memories between machines without dragging the whole central DB.

gnosys export project --to ./gnosys-public.json.gz       # auto-detects current project
gnosys export project <projectId> --to <bundle>          # explicit
gnosys import project <bundle> --strategy merge          # default — skip existing
gnosys import project <bundle> --strategy replace        # wipe target project first
gnosys import project <bundle> --strategy new-id         # remap to a fresh project ID

Bundles are gzipped JSON containing the project row, memories (with embeddings inline), relationships, and audit log. Lossless round-trip with the same DB schema; partially compatible across versions via the bundle manifest.

For an Obsidian-compatible markdown vault, use gnosys export vault --to <dir> (the v5.5.x form gnosys export --to <dir> keeps working).

Web Knowledge Base

Turn any website into a searchable knowledge base for AI chatbots. No database required. Works on Vercel, Netlify, Cloudflare Pages, or any platform that can serve files.

Quick Start

cd your-nextjs-site
npm install -g gnosys
gnosys init
gnosys web init
# Edit gnosys.json to set your sitemapUrl
gnosys web build
# Add to package.json: "postbuild": "gnosys web build"

How It Works

DEVELOPMENT TIME (local machine)
─────────────────────────────────
gnosys web init          → scaffolds /knowledge/ dir, adds config to gnosys.json
gnosys web ingest        → crawls site → converts to markdown → writes /knowledge/*.md
gnosys web build-index   → reads /knowledge/*.md → produces /knowledge/gnosys-index.json
gnosys web build         → runs ingest + build-index in one shot

All files committed to git. Deployed with the app.

RUNTIME (serverless / any host)
───────────────────────────────
import { loadIndex, search } from 'gnosys/web'

1. loadIndex('knowledge/gnosys-index.json')     → loads pre-computed index into memory
2. search(index, userMessage, { limit: 6 })     → returns ranked document references
3. Read matched .md files from filesystem         → inject content into LLM prompt
4. Call Claude/GPT/etc with focused context       → respond to user

No SQLite. No database. No network calls for search.

Integration Example (Next.js)

// app/api/chat/route.ts
import { loadIndex, search } from 'gnosys/web'
import { readFileSync } from 'fs'
import { join } from 'path'

const index = loadIndex(join(process.cwd(), 'knowledge', 'gnosys-index.json'))

export async function POST(req: Request) {
  const { message } = await req.json()

  const results = search(index, message, { limit: 6 })
  const context = results.map(r =>
    readFileSync(join(process.cwd(), 'knowledge', r.document.path), 'utf8')
  ).join('\n\n---\n\n')

  // Pass context to your LLM of choice
  const response = await callLLM({
    system: `Answer using ONLY the provided context.\n\nContext:\n${context}`,
    message
  })

  return Response.json({ reply: response })
}

Web CLI Commands

Command	Description
`gnosys web init`	Scaffold knowledge directory and config
`gnosys web ingest`	Crawl source and generate knowledge markdown
`gnosys web build-index`	Generate search index from knowledge files
`gnosys web build`	Run ingest + build-index in one shot
`gnosys web add <url>`	Ingest a single URL
`gnosys web remove <path>`	Remove a knowledge file and rebuild index
`gnosys web status`	Show knowledge base status

Configuration

Add to gnosys.json:

{
  "web": {
    "source": "sitemap",
    "sitemapUrl": "https://yoursite.com/sitemap.xml",
    "outputDir": "./knowledge",
    "exclude": ["/api", "/admin", "/_next"],
    "categories": {
      "/blog/*": "blog",
      "/services/*": "services",
      "/products/*": "products",
      "/about*": "company"
    },
    "llmEnrich": true,
    "prune": false
  }
}

The `/knowledge/` Directory

gnosys web build generates a /knowledge/ directory containing:

Markdown files — one per page, with YAML frontmatter (title, category, tags, relevance keywords, source URL, content hash)
gnosys-index.json — pre-computed TF-IDF inverted index for sub-5ms in-memory search
All files commit to git and deploy with your app — the knowledge base and the site are always in sync

This directory is the bridge between your website content and any AI system. Sir Chats-A-Lot uses it to power website chatbots with zero infrastructure.

Generative Engine Optimization (GEO)

The /knowledge/ markdown files double as a structured content layer for AI crawlers and LLM-powered search engines. To make your knowledge base discoverable:

Add a llms.txt file to your site root pointing to the knowledge directory
Reference individual markdown files in your llms.txt for fine-grained content exposure
YAML frontmatter provides structured metadata (title, category, tags) that LLMs can parse directly

This improves your site's visibility in AI-powered search results and enables LLMs to cite your content accurately.

SQLite vs Web Mode

Aspect	SQLite (default)	Web Knowledge Base
Storage	Central `~/.gnosys/gnosys.db`	Markdown files in repo
Search	FTS5 + optional embeddings	Pre-computed inverted index
Write support	Full CRUD	Read-only (build-time only)
Infrastructure	None (embedded SQLite)	None (files deploy with app)
Best for	Local agents, MCP, CLI	Web chatbots, serverless
Search latency	<10ms	<5ms (in-memory index)
Supports Dream Mode	Yes	No (read-only)

MCP Server Setup

The fastest way to wire gnosys into any supported client is to run gnosys init <ide> from the project directory you want memory-enabled. Examples:

gnosys init claude-desktop   # Claude Desktop (covers Chat, Cowork, and Code)
gnosys init claude           # Claude Code CLI
gnosys init cursor           # Cursor
gnosys init codex            # Codex
gnosys init gemini-cli       # Gemini CLI
gnosys init antigravity      # Google Antigravity

This does two things at once:

Wires gnosys into the IDE's MCP config (idempotent — safe to re-run).
Initializes the current directory as a gnosys project (creates .gnosys/gnosys.json, registers it in the central DB) so your memories can be scoped to it.

One-time vs. per-project

The IDE wiring writes to a user-level config file, so it only needs to happen once. Re-running it in another project just re-merges the same mcpServers.gnosys entry — harmless.

The project registration is per-directory: every codebase you want to be memory-aware of needs its own gnosys init. From then on, agents pass projectRoot: "/path/to/project" to gnosys MCP tools to scope memory to that codebase.

# Once, anywhere — wires Claude Desktop's MCP config:
gnosys init claude-desktop

# Once per project — registers the codebase in the central DB:
cd /path/to/project-a && gnosys init
cd /path/to/project-b && gnosys init

Cowork users: Cowork sessions don't have a working directory like a CLI does. The agent in Cowork uses whichever projectRoot it's told to use (typically auto-detected from open files or set via the system prompt). The "every working directory" question doesn't apply to Cowork itself — only to the projects you want memory-enabled. Run gnosys init claude-desktop once globally; run gnosys init per project.

Setup Wizards

gnosys setup runs the full interactive wizard. To configure just one piece without walking the whole thing, use one of these subcommands:

gnosys setup           # full wizard (provider, models, IDE, remote sync, dream)
gnosys setup models    # LLM provider + model only
gnosys setup remote    # multi-machine sync (NAS/shared drive)
gnosys setup dream     # Dream Mode designation, schedule, sub-tasks

Dream Mode setup (v5.4.2+)

Dream Mode is the idle-time consolidation engine — confidence decay, summary generation, self-critique, relationship discovery. With multi-machine sync (v5.3.0+), running dream cycles from every machine wastes work and fights for SQLite write locks. v5.4.2 introduces a single designated machine model:

Run gnosys setup dream on the machine you want to host dream cycles.
The wizard validates your provider/model with a live API probe before saving.
Other machines stay quiet — they see the designation in the central DB and skip the scheduler.
gnosys dream log shows recent runs; gnosys dashboard has a DREAM HEALTH section with last-run timestamp, designated machine, and consecutive-failure counter.
If the designated machine's LLM provider becomes unreachable, you'll see warnings at three layers: in audit log entries (dream_provider_unreachable), as stderr at MCP startup, and as a desktop notification after 3 consecutive failures.

Removed in v5.4.2

The following commands were removed in favor of the canonical gnosys setup <thing> form:

Removed	Use instead
`gnosys models`	`gnosys setup models`
`gnosys remote configure`	`gnosys setup remote`

gnosys remote push|pull|sync|status remain unchanged — only configure moved.

Manual config (if you prefer)

If you'd rather edit configs by hand, here's where each client looks for MCP servers.

Claude Desktop (Chat, Cowork, and Code share the same config)

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS), %APPDATA%\Claude\claude_desktop_config.json (Windows), or ~/.config/Claude/claude_desktop_config.json (Linux):

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

Restart Claude Desktop after editing.

Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

Claude Code

claude mcp add gnosys gnosys serve

Codex

Add to .codex/config.toml:

[mcp.gnosys]
type = "local"
command = ["gnosys", "serve"]

Gemini CLI

Add to ~/.gemini/settings.json (preserves any existing settings):

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

Antigravity

Add to ~/.gemini/antigravity/mcp_config.json:

{
  "mcpServers": {
    "gnosys": {
      "command": "gnosys",
      "args": ["serve"]
    }
  }
}

Antigravity reloads MCP servers automatically when you save the file.

Note: API keys are configured via gnosys setup (macOS Keychain, environment variable, or ~/.config/gnosys/.env). See LLM Provider Setup in the User Guide.

MCP Tools

Tool	Description
`gnosys_discover`	Find relevant memories by keyword (start here)
`gnosys_read`	Read a specific memory
`gnosys_search`	Full-text search across stores
`gnosys_hybrid_search`	Hybrid keyword + semantic search (RRF fusion)
`gnosys_semantic_search`	Semantic similarity search (embeddings)
`gnosys_ask`	Ask a question, get a synthesized answer with citations
`gnosys_reindex`	Rebuild semantic embeddings from all memories
`gnosys_list`	List memories with optional filters
`gnosys_lens`	Filtered views — combine category, tag, status, confidence, date filters
`gnosys_add`	Add a memory (LLM-structured)
`gnosys_add_structured`	Add with explicit fields (no LLM)
`gnosys_update`	Update frontmatter or content
`gnosys_reinforce`	Signal usefulness of a memory
`gnosys_commit_context`	Extract memories from conversation context
`gnosys_bootstrap`	Batch-import existing markdown documents
`gnosys_import`	Bulk import from CSV, JSON, or JSONL
`gnosys_init`	Initialize a new store
`gnosys_stale`	Find memories not modified within N days
`gnosys_history`	Version history for a memory (audit log)
`gnosys_rollback`	Rollback a memory to a previous version
`gnosys_timeline`	Show when memories were created/modified over time
`gnosys_stats`	Summary statistics for the memory store
`gnosys_links`	Show wikilinks and backlinks for a memory
`gnosys_graph`	Full cross-reference graph across all memories
`gnosys_maintain`	Run vault maintenance (decay, dedup, consolidation, archiving)
`gnosys_dearchive`	Force-dearchive memories from archive back to active
`gnosys_dashboard`	System dashboard (memory count, health, archive, graph, LLM status)
`gnosys_reindex_graph`	Build/rebuild the wikilink graph
`gnosys_dream`	Run a Dream Mode cycle (decay, self-critique, summaries, relationships)
`gnosys_export`	Export gnosys.db to an Obsidian-compatible vault
`gnosys_recall`	Fast memory injection for agent orchestrators (sub-50ms)
`gnosys_audit`	View structured audit trail of all memory operations
`gnosys_stores`	Show active stores, MCP roots, and detected project stores
`gnosys_tags`	List tag registry
`gnosys_tags_add`	Add a new tag to the registry
`gnosys_ingest_file`	Ingest a file (PDF, image, audio, video, DOCX) into memory
`gnosys_portfolio`	Portfolio dashboard — project status across all registered projects
`gnosys_update_status`	Guided 8-section status update checklist for AI agents
Centralized Brain
`gnosys_backup`	Create a point-in-time backup of the central DB
`gnosys_restore`	Restore the central DB from a backup
`gnosys_migrate_to_central`	Migrate project data into the central DB
`gnosys_preference_set`	Set a user preference (stored as scoped memory)
`gnosys_preference_get`	Get one or all preferences
`gnosys_preference_delete`	Delete a preference
`gnosys_sync`	Regenerate agent rules file from preferences + conventions
`gnosys_federated_search`	Tier-boosted search across project > user > global scopes
`gnosys_detect_ambiguity`	Check if a query matches multiple projects
`gnosys_briefing`	Generate project briefing (categories, activity, tags, summary)
`gnosys_working_set`	Get recently modified memories for the current project
Multi-Machine Sync
`gnosys_remote_status`	Check sync state (pending changes, conflicts, reachability)
`gnosys_remote_push`	Push local changes to remote
`gnosys_remote_pull`	Pull remote changes to local
`gnosys_remote_resolve`	Resolve a conflict by choosing local or remote

Key Features

Central Brain

All memories live in a single ~/.gnosys/gnosys.db with project_id and scope columns. SQLite is the sole source of truth — no dual-write, no markdown files on disk. Sub-10ms reads, WAL mode for concurrent access. Use gnosys export to generate an Obsidian vault on demand. See the User Guide for the full schema and memory format.

Multi-Machine Sync

Gnosys supports running across multiple machines with a shared database on a NAS or network share.

How it works:

Remote DB on a network share (e.g. /Volumes/nas/gnosys/) is the canonical source of truth
Local DB at ~/.gnosys/gnosys.db is an offline-resilience cache, not a performance optimization
Reads hit remote when reachable; fall back to local cache when remote is offline
Writes go to remote first; queue locally and auto-flush when offline
Per-memory modified timestamps detect conflicts; ULID memory IDs prevent collisions across concurrent writers
Skip-and-flag is the safe default; --newer-wins for unattended sync

Setup:

gnosys setup remote
# interactive: validates path, tests SQLite locking, checks latency

Daily commands:

gnosys remote status         # pending changes, conflicts, last sync
gnosys remote sync           # two-way sync (push then pull)
gnosys remote push           # local → remote only
gnosys remote pull           # remote → local only
gnosys remote resolve <id> --keep <local|remote>

AI-mediated conflict resolution: Agents using gnosys via MCP can detect sync state and prompt the user when conflicts arise, rather than silently picking a winner. The agent presents both versions and asks which to keep.

LLM Providers

Eight providers behind a single interface — switch between cloud and local with one command:

Provider	Type	Default Model	API Key Env Var
Anthropic	Cloud	claude-sonnet-4-6	`GNOSYS_ANTHROPIC_KEY`
Ollama	Local	llama3.2	— (runs locally)
Groq	Cloud	llama-3.3-70b-versatile	`GNOSYS_GROQ_KEY`
OpenAI	Cloud	gpt-4o-mini	`GNOSYS_OPENAI_KEY`
LM Studio	Local	default	— (runs locally)
xAI	Cloud	grok-3	`GNOSYS_XAI_KEY`
Mistral	Cloud	mistral-small-latest	`GNOSYS_MISTRAL_KEY`
Custom	Any	(user-defined)	`GNOSYS_CUSTOM_KEY`

Model lists and pricing are fetched dynamically from OpenRouter during gnosys setup and cached for 24 hours. Bundled defaults are used when offline.

API Key Security: gnosys setup offers three storage options: macOS Keychain (recommended — encrypted, no plaintext), environment variable (shell profile), or ~/.config/gnosys/.env (least secure). Legacy env var names (ANTHROPIC_API_KEY, GROQ_API_KEY, OPENAI_API_KEY, etc.) are still supported for backward compatibility.

Route tasks to different providers — a cheap model for structuring, a powerful model for synthesis:

{
  "llm": {
    "defaultProvider": "anthropic",
    "anthropic": { "model": "claude-sonnet-4-6" },
    "ollama": { "model": "llama3.2", "baseUrl": "http://localhost:11434" }
  },
  "taskModels": {
    "structuring": { "provider": "ollama", "model": "llama3.2" },
    "synthesis": { "provider": "anthropic", "model": "claude-sonnet-4-6" }
  }
}

Dream Mode

Idle-time consolidation inspired by biological memory: confidence decay, self-critique, summary generation, and relationship discovery. Runs automatically when the sandbox is idle, or manually with gnosys dream. Never deletes — only flags for review. See the User Guide for configuration and scheduling.

Federated Search

All search commands support --federated to search across project (1.5x boost), user (1.0x), and global (0.7x) scopes in the central DB. Recency adds a 1.3x boost, reinforcement count adds up to 25%. Results include scope and boosts fields so agents know where each memory came from. See the User Guide for details.

Process Tracing

gnosys trace ./src scans TypeScript/JavaScript files, extracts function declarations and call sites, then stores each as a procedural "how" memory with leads_to, follows_from, and requires relationships. gnosys traverse <id> walks relationship chains via BFS with depth limiting and type filtering. See the User Guide for details.

Obsidian Export

The primary store is the central gnosys.db. Use the Obsidian Export Bridge to generate a full vault:

gnosys export --to ~/vaults/my-project
gnosys export --to ~/vaults/my-project --overwrite
gnosys export --to ~/vaults/my-project --all   # summaries, reviews, graph data

Bulk Import

Import any structured dataset into atomic memories:

# JSON with field mapping
gnosys import foods.json --format json \
  --mapping '{"description":"title","foodCategory":"category","notes":"content"}' \
  --mode structured

# CSV
gnosys import data.csv --format csv \
  --mapping '{"name":"title","type":"category","notes":"content"}'

# JSONL (one record per line)
gnosys import events.jsonl --format jsonl \
  --mapping '{"event":"title","type":"category","details":"content"}'

Comparison

Aspect	Plain Markdown	RAG (Vector DB)	Knowledge Graph	Gnosys
Examples	CLAUDE.md, .cursorrules	Mem0, LangChain Memory	Graphiti/Zep, Mem0 Graph	—
Storage	`.md` files	Embeddings in vector DB	Nodes/edges in graph DB	Central SQLite DB (on-demand Obsidian export)
Transparency	Perfect	Lossy (embeddings)	High (query nodes)	High (SQLite + audit log + Obsidian export)
Version history	Git native	None built-in	None built-in	Audit log table in SQLite
Keyword search	Manual / grep	BM25 layer (some)	BM25 layer (some)	FTS5 (built-in)
Semantic search	None	Vector similarity	Graph + vectors	Vector + FTS5 hybrid (RRF)
Relationship traversal	None	None	Multi-hop graph queries	Wikilinks (manual encoding)
Scale comfort zone	~5K memories	100K+	100K+	100K+ (unified SQLite + archive tier)
Setup time	< 5 min	30 min - 2 hours	4 - 8 hours	15 - 30 min
Infrastructure	None	Vector DB + embeddings API	Graph DB + LLM	SQLite (embedded)
Human editability	Excellent	Poor (re-embed)	Moderate	Excellent
MCP integration	Via skill files	Custom server	Mem0 ships MCP	MCP server (included)
Obsidian compatible	Partially	No	No	Yes (full vault)
Cost	Free	$0-500+/mo (cloud DB + embeddings)	$250+/mo (Mem0 Pro) or self-host	Free (MIT)
Offline capable	Yes	Self-hosted only	Self-hosted only	Yes (Ollama/LM Studio)

CLI Reference

All commands support --json for programmatic output. See the User Guide for full details.

Getting started: setup, init, upgrade

Memory operations: add, add-structured, commit-context, read, update, reinforce, bootstrap, import

Search: discover, search, hybrid-search, semantic-search, ask, recall, fsearch

Views & analysis: list, lens, stale, timeline, stats, links, graph, tags, tags-add, audit

History: history, rollback

Maintenance: maintain, dearchive, dream, reindex, reindex-graph

Export & config: export, setup, config show, config set, dashboard, doctor, stores

Portfolio & status: status, status --global, status --web, portfolio, update-status

Centralized brain: backup, restore, migrate, pref set/get/delete, sync, ambiguity, briefing, working-set

Multimodal ingestion: ingest-file (PDF, image, audio, video, DOCX)

Sandbox: sandbox start/stop/status, helper generate

Web knowledge base: web init, web ingest, web build-index, web build, web add, web remove, web status

Multi-machine sync: remote status, remote sync, remote push, remote pull, remote resolve (configure via gnosys setup remote)

Server: serve, serve --with-maintenance

Development

npm install          # Install dependencies
npm run build        # Compile TypeScript
npm test             # Run test suite (738 tests)
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Run tests with v8 coverage report (HTML in coverage/)
npm run dev          # Run MCP server in dev mode (tsx)

738 tests across 35+ files. CI runs on Node 20 + 22 with multi-project scenario testing, network-share simulation, and TypeScript strict checking. Publishing uses OIDC trusted publishing via GitHub Actions — no npm tokens needed.

Architecture

src/
  index.ts            # MCP server — 50+ tools + gnosys://recall resource
  cli.ts              # CLI — full command suite with --json output
  lib/
    db.ts             # Central SQLite (6-table schema, project_id + scope)
    dbSearch.ts       # Adapter bridging GnosysDB to search interfaces
    dbWrite.ts        # DB write helpers (SQLite sole source of truth)
    migrate.ts        # Migration: v1.x -> v2.0 -> central DB
    dream.ts          # Dream Mode engine + idle scheduler
    export.ts         # Obsidian Export Bridge (gnosys.db -> vault)
    federated.ts      # Federated search, ambiguity detection, briefings
    preferences.ts    # User preferences as scoped memories
    rulesGen.ts       # Agent rules generation (GNOSYS:START/END blocks)
    store.ts          # Bootstrap/import of external markdown files
    search.ts         # FTS5 search and discovery
    embeddings.ts     # Lazy semantic embeddings (all-MiniLM-L6-v2)
    hybridSearch.ts   # Hybrid search with RRF fusion
    ask.ts            # Freeform Q&A with LLM synthesis + citations
    llm.ts            # LLM abstraction (8 providers + setup wizard)
    maintenance.ts    # Auto-maintenance: decay, dedup, archiving
    archive.ts        # Two-tier memory: active <-> archive
    recall.ts         # Ultra-fast recall for agent orchestrators
    audit.ts          # Structured audit logging
    graph.ts          # Persistent wikilink graph
    trace.ts          # Process tracing + reflection
    config.ts         # gnosys.json loader with Zod validation
    resolver.ts       # Layered multi-store resolution + MCP roots
    import.ts         # Bulk import engine (CSV, JSON, JSONL)
    portfolio.ts      # Portfolio dashboard (single/global project status)
    portfolioHtml.ts  # HTML dashboard renderer for gnosys status --web
    # Multimodal ingestion
    multimodalIngest.ts  # Orchestrator for multi-format file ingestion
    attachments.ts       # Attachment storage and linking
    pdfExtract.ts        # PDF text/structure extraction
    imageExtract.ts      # Image description via vision models
    audioExtract.ts      # Audio transcription
    videoExtract.ts      # Video transcription and frame extraction
    # Web Knowledge Base
    staticSearch.ts      # Zero-dep web search runtime (gnosys/web)
    structuredIngest.ts  # No-LLM fallback with TF-IDF keyword extraction
    webIndex.ts          # Build-time inverted index generator
    webIngest.ts         # Site crawler (sitemap -> markdown)
  sandbox/
    server.ts         # Unix socket server + Dream Mode scheduler
    client.ts         # Client for agent connections
    manager.ts        # Process lifecycle management

Benchmarks

Real numbers from a 120-memory test vault:

Metric	Result
Import 100 records (structured)	0.6s
Cold start (first load)	0.3s
Keyword search (FTS5)	<10ms
Hybrid search (keyword + semantic)	~50ms
Reindex 120 embeddings	~8s (first run downloads ~80 MB model)
Maintenance dry-run (120 memories)	~2s
Graph reindex (120 memories)	<1s
Storage per memory	~1 KB (SQLite row)
Embedding storage (120 memories)	~0.3 MB
Test suite	738 tests, 0 errors

All benchmarks on Apple M-series hardware, Node.js 20+. Structured imports bypass LLM entirely.

Community & Next Steps

Gnosys is open source (MIT) and actively developed. Here's how to get involved:

Get started fast:

Cursor template: Add Gnosys to any Cursor project with one MCP config line (see MCP Server Setup)
Docker: docker build -t gnosys . && docker compose up for containerized deployment

Contribute:

GitHub Discussions — share ideas, ask questions, show what you've built
Issues — bug reports and feature requests
PRs welcome — especially for new import connectors, LLM providers, and Obsidian plugins

What's next:

Improved network share latency (write-ahead batching for high-latency NAS)
Automated background sync via LaunchAgent (macOS) / systemd (Linux)
Temporal memory versioning (valid_from / valid_until)
Cross-session "deep dream" overnight consolidation
Graph visualization in the dashboard
Obsidian community plugin for native vault integration
Docker Hub published image for one-line deployment
Improved test coverage targets
Automated CHANGELOG generation

License

MIT — LICENSE

Name		Name	Last commit message	Last commit date
Latest commit History 102 Commits
.github/workflows		.github/workflows
docs		docs
extensions/vscode		extensions/vscode
prompts		prompts
src		src
.dockerignore		.dockerignore
.gitignore		.gitignore
AGENTS.md		AGENTS.md
CHANGELOG.md		CHANGELOG.md
CODE_OF_CONDUCT.md		CODE_OF_CONDUCT.md
CONTRIBUTING.md		CONTRIBUTING.md
DEMO.md		DEMO.md
Dockerfile		Dockerfile
LICENSE		LICENSE
README.md		README.md
docker-compose.yml		docker-compose.yml
package-lock.json		package-lock.json
package.json		package.json
tsconfig.json		tsconfig.json
vitest.config.ts		vitest.config.ts

Folders and files

Latest commit

History

Repository files navigation

Gnosys — One Brain. Zero Context Bloat.

Why Gnosys?

Quick Start

Agent / Helper Library

Interactive Chat (TUI)

Per-Project Bundles

Web Knowledge Base

Quick Start

How It Works

Integration Example (Next.js)

Web CLI Commands

Configuration

The /knowledge/ Directory

Generative Engine Optimization (GEO)

SQLite vs Web Mode

MCP Server Setup

One-time vs. per-project

Setup Wizards

Dream Mode setup (v5.4.2+)

Removed in v5.4.2

Manual config (if you prefer)

Claude Desktop (Chat, Cowork, and Code share the same config)

Cursor

Claude Code

Codex

Gemini CLI

Antigravity

MCP Tools

Key Features

Central Brain

Multi-Machine Sync

LLM Providers

Dream Mode

Federated Search

Process Tracing

Obsidian Export

Bulk Import

Comparison

CLI Reference

Development

Architecture

Benchmarks

Community & Next Steps

License

About

Topics

Resources

License

Code of conduct

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

The `/knowledge/` Directory

Packages